---
title: Selection Plugin
description: Enables text selection in Vue, providing visual highlighting and an API to copy or process the selected text.
searchable: true
---

# Selection Plugin

The Selection Plugin enables users to select text within the PDF document, just like on a standard webpage. It provides the `<SelectionLayer />` to visually highlight the selected text and a rich API to get the selected content.

## Installation

This plugin depends on the `Interaction Manager` plugin. You must install both packages.

```sh npm2yarn
npm install @embedpdf/plugin-selection @embedpdf/plugin-interaction-manager
````

## Registration

Import `SelectionPluginPackage` and its `InteractionManager` dependency, and add them to the `plugins` array. The Selection plugin should be registered after its dependency.

```typescript {4, 14}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/vue'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/vue'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),

  // Register dependency first
  createPluginRegistration(InteractionManagerPluginPackage),

  // Register the selection plugin
  createPluginRegistration(SelectionPluginPackage),
]
```

## Usage

The plugin has two main parts: the `<SelectionLayer />` component for the UI, and the `useSelectionCapability` composable for interacting with the selection data.

### 1\. Displaying the Selection

To show the highlighted text, place the `<SelectionLayer />` component inside the default slot of your `<Scroller />`. For text selection to work correctly, it must be a child of the `PagePointerProvider`.

```vue {3, 16}
<script setup lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/vue';
import { SelectionLayer } from '@embedpdf/plugin-selection/vue';
</script>
<template>
  <Scroller>
    <template #default="{ page }">
      <PagePointerProvider
        :page-index="page.pageIndex"
        :page-width="page.width"
        :page-height="page.height"
        :rotation="page.rotation"
        :scale="page.scale"
      >
        <RenderLayer :page-index="page.pageIndex" :scale="page.scale" />
        <SelectionLayer :page-index="page.pageIndex" :scale="page.scale" />
      </PagePointerProvider>
    </template>
  </Scroller>
</template>
```

### 2\. Interacting with the Selection

The `useSelectionCapability` composable allows you to work with the selected text. You can create a toolbar to copy the text or perform other actions. The plugin automatically handles the clipboard logic when you call `provides.value.copyToClipboard()`.

You can use the `onSelectionChange` event to know when a selection exists, which is useful for enabling or disabling UI elements like a "Copy" button.

```vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { useSelectionCapability, type SelectionRangeX } from '@embedpdf/plugin-selection/vue';

const { provides: selection } = useSelectionCapability();
const hasSelection = ref(false);
let unsubscribe: (() => void) | undefined;

onMounted(() => {
  if (!selection.value) return;
  unsubscribe = selection.value.onSelectionChange((sel: SelectionRangeX | null) => {
    hasSelection.value = !!sel;
  });
});

onUnmounted(() => {
  unsubscribe?.();
});
</script>

<template>
  <button @click="selection?.copyToClipboard()" :disabled="!hasSelection">Copy</button>
</template>
```

## Live Example

Try selecting text in the viewer below. A "Copy Text" button will become active, allowing you to copy the selected content to your clipboard.

import { SelectionExample } from '../code-examples/selection-example';

<SelectionExample />

## API Reference

### Component: `<SelectionLayer />`

The component that renders the blue rectangles over the selected text.

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | **(Required)** The index of the page this layer is on. |
| **`scale`** | `number` | **(Required)** The current scale of the page. |
| **`background`** | `string` | (Optional) The color of the selection highlight. <br />**Default**: `'rgba(33,150,243)'` |

### Composable: `useSelectionCapability()`

Connects your component to the selection plugin's state and functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`** | `Ref<SelectionCapability \| null>` | A ref object with methods to interact with the selection, or `null` if the plugin is not ready. |

#### `SelectionCapability` Methods

| Method | Description |
| :--- | :--- |
| **`copyToClipboard()`** | Triggers the process to copy the currently selected text to the user's clipboard. |
| **`getSelectedText()`** | Returns a `Task<string[]>` that resolves with the selected text content. Each string in the array is a line. |
| **`getFormattedSelection()`** | Returns an array of objects describing the selection on each page, including its bounding box and the individual highlight rectangles. |
| **`onSelectionChange(cb)`** | Subscribes to when the text selection is created, updated, or cleared. Returns an `unsubscribe` function. |
| **`onEndSelection(cb)`** | Subscribes to when the user finishes selecting text (on mouse up). This is ideal for fetching the selected text content. Returns an `unsubscribe` function. |